package xx.services.entity.inter;

import javax.servlet.http.HttpServletResponse;
import javax.ws.rs.DefaultValue;
import javax.ws.rs.FormParam;
import javax.ws.rs.PathParam;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.Context;

/**
 * 分类服务接口<br>
 * 
 * @Path (Constants.RESTFUL_ROOT_PATH + "/category")
 * @author chenx
 */
public interface ICategoryInterface
{
    /**
     * 指定在某分类{category_id}下增加子分类。<br>
     * 
     * @POST
     * @Path ("/{category_id}")
     * @param categoryId
     *            -@PathParam("category_id") 分类ID，必须大于0
     * @param name
     *            -@FormParam("name") 分类名称
     * @param description
     *            -@FormParam("description") 描述
     * @return 新增Category的JSON字符串数据
     */
    public String addCategory(@PathParam("category_id")
    long categoryId, @FormParam("keyword")
    String keyword, @FormParam("name")
    String name, @FormParam("description")
    String description);

    /**
     * 指定在某分类{category_id}下增加实体。<br>
     * 
     * @POST
     * @Path ("/{category_id}/entity")
     * @param categoryId
     *            -@PathParam("category_id") 指定分类ID
     * @param title
     *            -@FormParam("title") 标题
     * @param content
     *            -@FormParam("content") 内容
     * @param url
     *            -@FormParam("url") URL地址
     * @param fileId
     *            -@FormParam("file_id") 指定关联文件ID
     * @param tags
     *            -@FormParam("tags") 实体tag标签，多个tag标签用空格“ ”隔开
     * @param value
     *            -@FormParam("value") 实体扩展属性的json数据 add by dengjinye 20130512
     * @return 新增的实体
     * @author dengjinye,2010-12-6
     */
    public String addEntity(@PathParam("category_id")
    long categoryId, @FormParam("title")
    String title, @FormParam("content")
    String content, @FormParam("url")
    String url, @FormParam("file_id")
    long fileId, @FormParam("tags")
    String tags, @FormParam("value")
    String value);

    /**
     * 指定为某新闻分类{category_id}增加一个新闻抓取规则。<br>
     * 
     * @POST
     * @Path ("/{category_id}/rule")
     * @param categoryId
     *            -@PathParam("category_id") 指定分类ID
     * @param titleRule
     *            -@FormParam("title_rule") 标题
     * @param contentRule
     *            -@FormParam("content_rule") 内容
     * @param url
     *            -@FormParam("url") URL地址
     * @param encoding
     *            -@FormParam("encoding") 编码方式
     * @return
     * @author 陈祥 2011-8-19
     */
    public String addNewsRule(@PathParam("category_id")
    long categoryId, @FormParam("title_rule")
    String titleRule, @FormParam("content_rule")
    String contentRule, @FormParam("url")
    String url, @FormParam("encoding")
    String encoding);

    /**
     * 获取指定新闻分类{category_id}下的所有新闻抓取规则。<br>
     * 
     * @GET
     * @Path ("/{category_id}/rule")
     * @param categoryId
     *            -@PathParam("category_id") 指定分类ID
     * @return
     * @author 陈祥 2011-8-19
     */
    public String getNewsRule(@PathParam("category_id")
    long categoryId);

    /**
     * 修改某新闻分类{category_id}下的某条新闻抓取规则{rule_id}。<br>
     * 
     * @PUT
     * @Path ("/{category_id}/rule")
     * @param categoryId
     *            -@PathParam("category_id") 指定分类ID
     * @param titleRule
     *            -@FormParam("title_rule") 标题
     * @param contentRule
     *            -@FormParam("content_rule") 内容
     * @param url
     *            -@FormParam("url") URL地址
     * @param ruleId
     *            -@FormParam("rule_id") URL地址
     * @param encoding
     *            -@FormParam("encoding") 编码方式
     * @return
     * @author 陈祥 2011-8-19
     */
    public String updateNewsRule(@PathParam("category_id")
    long categoryId, @FormParam("title_rule")
    String titleRule, @FormParam("content_rule")
    String contentRule, @FormParam("url")
    String url, @PathParam("rule_id")
    long ruleId, @FormParam("encoding")
    String encoding);

    /**
     * 删除某新闻分类{category_id}下的新闻抓取规则{rule_ids}。<br>
     * 
     * @DELETE
     * @Path ("/{category_id}/rule")
     * @param categoryId
     *            -@PathParam("category_id") 指定分类ID
     * @param ruleIds
     *            -@PathParam("rule_ids") 规则ID集，多个ID间用“_”隔开
     * @return
     * @author 陈祥 2011-8-19
     */
    public String deleteNewsRule(@PathParam("category_id")
    long categoryId, @PathParam("rule_ids")
    String ruleIds);

    /**
     * 修改分类{category_id}。<br>
     * 
     * @PUT
     * @Path ("/{category_id}")
     * @param categoryId
     *            -@PathParam("category_id") 分类ID
     * @param name
     *            -@FormParam("name") 分类名称
     * @param description
     *            -@FormParam("description") 描述
     * @return 新增Category的JSON字符串数据
     */
    public String updateCategory(@PathParam("category_id")
    long categoryId, @FormParam("name")
    String name, @FormParam("keyword")
    String keyword, @FormParam("description")
    String description);

    /**
     * 描述：删除分类{category_id}。<br>
     * 注：删除此分类时，连同子分类也要一起删除。
     * 
     * @DELETE
     * @Path ("/{category_id}")
     * @param categoryId
     *            -@PathParam("category_id") 分类ID，多个分类ID用“_”连接
     * @return
     */
    public String deleteCategory(@PathParam("category_id")
    long categoryId);

    /**
     * 把分类{category_id}移动到分类{category_id2}下。<br>
     * 
     * @PUT
     * @Path ("/{category_id1}/to/{category_id2}")
     * @param categoryId1
     *            -@PathParam("category_id1")
     * @param categoryId2
     *            -@PathParam("category_id2")
     * @return
     * @throws Exception
     *             String 下午09:33:50
     * @author dengjinye
     */
    public String moveCategory(@PathParam("category_id1")
    long categoryId1, @PathParam("category_id2")
    long categoryId2);

    /**
     * 把分类{category_id1}排到分类{category_id2}<br>
     * 的前边或后边（当{category_id2}>0时表示排到{category_id2}的后边，当<br>
     * {category_id2}<0时表示排到{category_id2}的前边），注：{category_id2}<0<br>
     * 就是在{category_id2}前加负号(-)。<br>
     * 
     * @PUT
     * @Path ("/{category_id1}/sort/{category_id2}")
     * @param categoryId1
     *            -@PathParam("category_id1")
     * @param categoryId2
     *            -@PathParam("category_id2")
     * @return String 下午09:52:56
     * @author dengjinye
     */
    public String sortCategory(@PathParam("category_id1")
    long categoryId1, @PathParam("category_id2")
    long categoryId2);

    /**
     * 指定获取某分类{category_id}下的第一级节点。<br>
     * 
     * @GET
     * @Path ("/{category_id}/children")
     * @param categoryId
     *            -@PathParam("category_id") 分类ID
     * @return category列表
     * @throws Exception
     *             String 下午09:28:30
     * @author dengjinye
     */

    public String getCategoryChildren(@PathParam("category_id")
    long categoryId);

    /**
     * 指定获取单个分类{category_id}的信息。<br>
     * 包含与此分类关联的附件类型、tag等。
     * 
     * @GET HTTP请求类型
     * @Path ("/{category_id}")
     * @param categoryId
     *            -@PathParam("category_id") 分类ID
     * @return Category的JSON字符串数据
     */
    public String getCategory(@PathParam("category_id")
    long categoryId);

    /**
     * 获取某分类{category_id}下的实体列表。
     * 
     * @GET
     * @Path ("/{category_id}/entity")
     * @param categoryId
     * @param entity
     *            实体名称，如产品为(product)、文档为(document)等，与sign的功能是一样的，当sign为0时，此参数生效
     * @param onlyCurCategory
     *            是否只获取当前分类下的实体<br>
     *            默认为false，获取当前分类下的所有子分类下的实体<br>
     * @return String 下午09:45:49
     * @author dengjinye
     */
    public String getEntityList(@PathParam("category_id")
    long categoryId, @QueryParam("entity")
    String entity, @QueryParam("only_cur_category")
    boolean onlyCurCategory);

    /**
     * 导出某分类{category_id}下的实体列表。
     * 
     * @GET
     * @Path ("/{category_id}/export")
     * @param categoryId
     * @param sign
     *            分类标志，当categoryId为0时生效
     * @param entity
     *            实体名称，如产品为(product)、文档为(document)等，与sign的功能是一样的，当sign为0时，此参数生效
     * @param onlyCurCategory
     *            是否只获取当前分类下的实体<br>
     *            默认为false，获取当前分类下的所有子分类下的实体<br>
     * @param sumFields
     *            entity表格中需要进行统计的字段
     * @param sumEntityExtFields
     *            entity_ext扩展表中需要进行统计的字段
     * @return String 下午09:45:49
     * @author dengjinye
     */
    public String exportEntityList(@Context
    HttpServletResponse response, @PathParam("category_id")
    long categoryId, @QueryParam("sign")
    int sign, @QueryParam("entity")
    String entity, @QueryParam("only_cur_category")
    boolean onlyCurCategory, @QueryParam("sumFields")
    String sumFields, @QueryParam("sumEntityExtFields")
    String sumEntityExtFields);

    /**
     * 执行规则
     * 
     * @POST
     * @Path("/rule/{rule_id ")
     * @param ruleId
     *            规则ID集
     * @return
     * @author 陈祥 2011-8-29
     */
    public String excuteRule(@PathParam("rule_id")
    String ruleId);

    /**
     * 描述：获取category的档案，包含扩展属性. <br>
     * 1.获取category_id对应的所有档案 <br>
     * 2.获取category_id下指定分类({type_id|keyword})对应的档案属性。 输入： 输出：档案JSON数据 [ { detail_id, category_id,
     * type_id, rule, error, single, keyword, [ { value_id, attribute_id, title, value, rule, error,
     * datatype, opvalue } ] } ]
     * 
     * @GET
     * @Path("/{category_id /datum")<br>
     * @param categoryId
     * @return
     * @author dengjinye,2011-2-21
     */
    public String getDatumByCategory(@PathParam("category_id")
    long categoryId);

    /**
     * 根据categoryId获取此目录中entity的横向属性定义字段
     * 
     * @GET
     * @Path("/{category_id/extdefined")<br>
     * @param categoryId
     * @return
     * @author dengjinye,2013-5-21
     */
    public String getExtDefinedByCategory(@PathParam("category_id")
    long categoryId);

    /**
     * 更新categoryId的横向属性字段
     * 
     * @PUT
     * @Path("/{category_id /extdefined")<br>
     * @param categoryId
     * @param title
     *            横向属性title
     * @param showFields
     *            需要显示的字段，多个字段间用逗号“,”间隔
     * @return
     * @author dengjinye 2013-5-21
     */
    public String updateExtDefined(@PathParam("category_id")
    long categoryId, @QueryParam("title")
    String title, @QueryParam("show_fields")
    String showFields);

    /**
     * 统计指定字段的总计
     * @param categoryId
     * @param entity
     * @param onlyCurCategory
     *          是否只查询当前category
     * @param sumFields
     *          需要统计的entity的基本字段
     * @param sumEntityExtFields
     *          需要统计的entityExt的字段
     * @return
     */
    public String getEntitySumTotal(@PathParam("category_id")
    long categoryId, @QueryParam("entity")
    String entity, @DefaultValue("true")
    @QueryParam("only_cur_category")
    boolean onlyCurCategory, @QueryParam("sumFields")
    String sumFields, @QueryParam("sumEntityExtFields")
    String sumEntityExtFields);
}
